home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 July: Mac OS SDK / Dev.CD Jul 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Interfaces / PInterfaces / Translation.p < prev    next >
Encoding:
Text File  |  1995-07-06  |  11.8 KB  |  320 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        Translation.p
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Package:    Universal Interfaces 2.1 in “MPW Latest” on ETO #18
  8.  
  9.      Copyright:    © 1984-1995 by Apple Computer, Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13.                  stack.  Include the file and version information (from above)
  14.                  in the problem description and send to:
  15.                      Internet:    apple.bugs@applelink.apple.com
  16.                      AppleLink:    APPLE.BUGS
  17.  
  18. }
  19.  
  20. {$IFC UNDEFINED UsingIncludes}
  21. {$SETC UsingIncludes := 0}
  22. {$ENDC}
  23.  
  24. {$IFC NOT UsingIncludes}
  25.  UNIT Translation;
  26.  INTERFACE
  27. {$ENDC}
  28.  
  29. {$IFC UNDEFINED __TRANSLATION__}
  30. {$SETC __TRANSLATION__ := 1}
  31.  
  32. {$I+}
  33. {$SETC TranslationIncludes := UsingIncludes}
  34. {$SETC UsingIncludes := 1}
  35.  
  36.  
  37. {$IFC UNDEFINED __TYPES__}
  38. {$I Types.p}
  39. {$ENDC}
  40. {    ConditionalMacros.p                                            }
  41.  
  42. {$IFC UNDEFINED __FILES__}
  43. {$I Files.p}
  44. {$ENDC}
  45. {    MixedMode.p                                                    }
  46. {    OSUtils.p                                                    }
  47. {        Memory.p                                                }
  48. {    Finder.p                                                    }
  49.  
  50. {$IFC UNDEFINED __COMPONENTS__}
  51. {$I Components.p}
  52. {$ENDC}
  53.  
  54. {$IFC UNDEFINED __TRANSLATIONEXTENSIONS__}
  55. {$I TranslationExtensions.p}
  56. {$ENDC}
  57. {    Quickdraw.p                                                    }
  58. {        QuickdrawText.p                                            }
  59.  
  60. {$PUSH}
  61. {$ALIGN MAC68K}
  62. {$LibExport+}
  63.     
  64. TYPE
  65.     DocOpenMethod = INTEGER;
  66.  
  67.  
  68. CONST
  69.     domCannot                    = 0;
  70.     domNative                    = 1;
  71.     domTranslateFirst            = 2;
  72.     domWildcard                    = 3;
  73.  
  74. { 0L terminated array of OSTypes, or FileTypes}
  75.     
  76. TYPE
  77.     TypesBlock = ARRAY [0..63] OF OSType;
  78.  
  79.     TypesBlockPtr = ^OSType;
  80.  
  81. { Progress dialog resource ID}
  82.  
  83. CONST
  84.     kTranslationScrapProgressDialogID = -16555;
  85.  
  86. { block of data that describes how to translate}
  87.  
  88. TYPE
  89.     FileTranslationSpec = RECORD
  90.         componentSignature:        OSType;
  91.         translationSystemInfo:    Ptr;
  92.         src:                    FileTypeSpec;
  93.         dst:                    FileTypeSpec;
  94.     END;
  95.  
  96.     FileTranslationSpecArrayPtr = ^FileTranslationSpec;
  97.  
  98. {****************************************************************************************
  99. * 
  100. *   GetFileTypesThatAppCanNativelyOpen
  101. * 
  102. *  This routine returns a list of all FileTypes that an application can open by itself
  103. * 
  104. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  105. *             appSignature        signature (creator) of application
  106. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  107. * 
  108. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  109. }
  110.  
  111. FUNCTION GetFileTypesThatAppCanNativelyOpen(appVRefNumHint: INTEGER; appSignature: OSType; VAR nativeTypes: FileType): OSErr;
  112.     {$IFC NOT GENERATINGCFM}
  113.     INLINE $701C, $ABFC;
  114.     {$ENDC}
  115. {****************************************************************************************
  116. * 
  117. *  ExtendFileTypeList
  118. * 
  119. *  This routine makes a new list of file types that can be translated into a type in the given list
  120. *  Used by StandardFile
  121. * 
  122. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  123. *             numberOriginalTypes        number of file types in orgTypeList
  124. *              extendedTypeList        pointer to a buffer to be filled with file types
  125. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  126. * 
  127. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  128. *             numberExtendedTypes        number of file types put in extendedTypeList
  129. }
  130. FUNCTION ExtendFileTypeList({CONST}VAR originalTypeList: FileType; numberOriginalTypes: INTEGER; VAR extendedTypeList: FileType; VAR numberExtendedTypes: INTEGER): OSErr;
  131.     {$IFC NOT GENERATINGCFM}
  132.     INLINE $7009, $ABFC;
  133.     {$ENDC}
  134. {****************************************************************************************
  135. * 
  136. * 
  137. *  This routine checks if a file can be opened by a particular application.
  138. *  If so, it returns if it needs to be translated first, and if so then how.
  139. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  140. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  141. * 
  142. *  Enter:    targetDocument        document to check if it can be opened
  143. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  144. *             appSignature        signature (creator) of application to open doc
  145. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  146. *             onlyNative            whether to consider if document can be translated before opening
  147. *             howToOpen            pointer to buffer in which to put how the document can be opened
  148. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  149. * 
  150. *  Exit:    howToOpen            whether file needs to be translated to be read
  151. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  152. *             returns                noErr, noPrefAppErr
  153. }
  154. FUNCTION CanDocBeOpened({CONST}VAR targetDocument: FSSpec; appVRefNumHint: INTEGER; appSignature: OSType; {CONST}VAR nativeTypes: FileType; onlyNative: BOOLEAN; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): OSErr;
  155.     {$IFC NOT GENERATINGCFM}
  156.     INLINE $701E, $ABFC;
  157.     {$ENDC}
  158. {****************************************************************************************
  159. * 
  160. *  GetFileTranslationPaths
  161. * 
  162. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  163. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  164. * 
  165. *  Enter:    srcDoc            source file or NULL for all matches
  166. *             dstDoc            destination FileType or NULL for all matches
  167. *             maxResultCount
  168. *             resultBuffer
  169. *  Exit:    number of paths
  170. }
  171. FUNCTION GetFileTranslationPaths(VAR srcDocument: FSSpec; dstDocType: FileType; maxResultCount: INTEGER; resultBuffer: FileTranslationSpecArrayPtr): INTEGER;
  172.     {$IFC NOT GENERATINGCFM}
  173.     INLINE $7038, $ABFC;
  174.     {$ENDC}
  175. {****************************************************************************************
  176. * 
  177. *  GetPathFromTranslationDialog
  178. * 
  179. *  This routine, with a given document, application, and a passed typelist will display the
  180. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  181. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  182. *  The routine returns the translation path information.
  183. * 
  184. *  Enter:    theDocument            FSSpec to document to open
  185. *             theApplication        FSSpec to application to open document
  186. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  187. *                                 you would like the documented translated to.  Order most perferred
  188. *                                 to least.
  189. * 
  190. *  Exit:    howToOpen            Translation method needed to open document
  191. *             howToTranslate        Translation specification
  192. *             returns                Any errors that might occur.
  193. }
  194. FUNCTION GetPathFromTranslationDialog({CONST}VAR theDocument: FSSpec; {CONST}VAR theApplication: FSSpec; typeList: TypesBlockPtr; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): OSErr;
  195.     {$IFC NOT GENERATINGCFM}
  196.     INLINE $7037, $ABFC;
  197.     {$ENDC}
  198. {****************************************************************************************
  199. * 
  200. *   TranslateFile
  201. * 
  202. *  This routine reads a file of one format and writes it to another file in another format. 
  203. *  The information on how to translated is generated by the routine CanDocBeOpened.
  204. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  205. *  The destination file must not exist.  It is created by this routine.  
  206. * 
  207. *  Enter:    sourceDocument            input file to translate
  208. *             destinationDocument        output file of translation
  209. *             howToTranslate            pointer to info on how to translate
  210. *  Exit:    returns                    noErr, badTranslationSpecErr 
  211. }
  212. FUNCTION TranslateFile({CONST}VAR sourceDocument: FSSpec; {CONST}VAR destinationDocument: FSSpec; {CONST}VAR howToTranslate: FileTranslationSpec): OSErr;
  213.     {$IFC NOT GENERATINGCFM}
  214.     INLINE $700C, $ABFC;
  215.     {$ENDC}
  216. {****************************************************************************************
  217. * 
  218. *   GetDocumentKindString
  219. * 
  220. *  This routine returns the string the Finder should show for the "kind" of a document
  221. *  in the GetInfo window and in the kind column of a list view.  
  222. * 
  223. *  Enter:    docVRefNum        The volume containing the document
  224. *             docType            The catInfo.fdType of the document
  225. *             docCreator        The catInfo.fdCreator of the document
  226. *             kindString        pointer to where to return the string
  227. * 
  228. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  229. *             returns            noErr, or afpItemNoFound if kind could not be determined
  230. }
  231. FUNCTION GetDocumentKindString(docVRefNum: INTEGER; docType: OSType; docCreator: OSType; VAR kindString: Str63): OSErr;
  232.     {$IFC NOT GENERATINGCFM}
  233.     INLINE $7016, $ABFC;
  234.     {$ENDC}
  235. {****************************************************************************************
  236. * 
  237. *  GetTranslationExtensionName
  238. * 
  239. *  This routine returns the translation system name from a specified TranslationSpec
  240. * 
  241. *  Enter:    translationMethod    The translation path to get the translation name from
  242. * 
  243. *  Exit:    extensionName        The name of the translation system
  244. *             returns                Any errors that might occur
  245. }
  246. FUNCTION GetTranslationExtensionName({CONST}VAR translationMethod: FileTranslationSpec; VAR extensionName: Str31): OSErr;
  247.     {$IFC NOT GENERATINGCFM}
  248.     INLINE $7036, $ABFC;
  249.     {$ENDC}
  250. {****************************************************************************************
  251. * 
  252. *  GetScrapDataProcPtr
  253. * 
  254. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  255. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  256. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  257. *  with a list all the formats that you have available to be translated, and the length of each.
  258. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  259. *  the formats that 'fmts' list said was available.
  260. * 
  261. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  262. *             dataH                    Handle in which to put the requested data
  263. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  264. *             
  265. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  266. }
  267. TYPE
  268.     GetScrapDataProcPtr = ProcPtr;  { FUNCTION GetScrapData(requestedFormat: ScrapType; dataH: Handle; srcDataGetterRefCon: UNIV Ptr): OSErr; }
  269.     GetScrapDataUPP = UniversalProcPtr;
  270.  
  271. CONST
  272.     uppGetScrapDataProcInfo = $00000FE0; { FUNCTION (4 byte param, 4 byte param, 4 byte param): 2 byte result; }
  273.  
  274. FUNCTION NewGetScrapDataProc(userRoutine: GetScrapDataProcPtr): GetScrapDataUPP;
  275.     {$IFC NOT GENERATINGCFM }
  276.     INLINE $2E9F;
  277.     {$ENDC}
  278.  
  279. FUNCTION CallGetScrapDataProc(requestedFormat: ScrapType; dataH: Handle; srcDataGetterRefCon: UNIV Ptr; userRoutine: GetScrapDataUPP): OSErr;
  280.     {$IFC NOT GENERATINGCFM}
  281.     INLINE $205F, $4E90;
  282.     {$ENDC}
  283.     
  284. TYPE
  285.     GetScrapData = GetScrapDataUPP;
  286.  
  287. {****************************************************************************************
  288. * 
  289. *  TranslateScrap
  290. * 
  291. *  This routine resizes the destination handle and fills it with data of the requested format.
  292. *  The data is generated by translated one or more source formats of data supplied by
  293. *  the procedure srcDataGetter.  
  294. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  295. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  296. * 
  297. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  298. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  299. *             destinationFormat            Format of data desired
  300. *             destinationData                Handle in which to store translated data
  301. *             
  302. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  303. }
  304.  
  305. FUNCTION TranslateScrap(sourceDataGetter: GetScrapData; sourceDataGetterRefCon: UNIV Ptr; destinationFormat: ScrapType; destinationData: Handle; progressDialogID: INTEGER): OSErr;
  306.     {$IFC NOT GENERATINGCFM}
  307.     INLINE $700E, $ABFC;
  308.     {$ENDC}
  309.  
  310. {$ALIGN RESET}
  311. {$POP}
  312.  
  313. {$SETC UsingIncludes := TranslationIncludes}
  314.  
  315. {$ENDC} {__TRANSLATION__}
  316.  
  317. {$IFC NOT UsingIncludes}
  318.  END.
  319. {$ENDC}
  320.